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IBM 7040/7044 Operating System (1G/32K) 
Debugging Facilities 



This publication describes the 7040/7044 (16/32K) Operating 
System Debugging Package and the dump routines available with 
the 7040/7044 Operating System, Version 9. The Debugging 
Package is a programming aid that enables the user to obtain 
dynamic dumps of specified areas of core storage and machine 
registers during program execution. 

Among the subjects discussed in this publication are Compile- 
Time Debugging for cobol programs, Load-Time Debugging for 
Fortran and map programs, Dump Routines and Parameters, 
and the Snapshot Routine. 







Preface 



The ibm 7040/7044 Operating System Debugging 
Package provides a means of taking highly selective 
dumps of core storage areas and machine registers 
with a minimum of programming effort. By carefully 
selecting the areas to be dumped and the time at 
which to dump them, the user can obtain information 
valuable in locating and correcting program errors. 
The facilities described in this publication pertain to 
Fortran iv, cobol, and map program debugging. 

As a prerequisite to understanding this publication, 
the reader should be familiar with the ibjob Processor, 
as described in the ibm publications IBM 7040/7044 
Operating System (16/32K): Programmer's Guide, and 
IBM 7040/7044 Operating System (16/32K): Opera- 
tor's Guide. He should also be familiar with at least one 
of the programming languages accepted by the proc- 
essor that are described in the following ibm publi- 
cations: 

IBM 7040/7044 Operating System (16/32K): Macro 
Assembly Program (map) Language, Form C28- 
6335. 

IBM 7040/7044 Operating System (16/32): FOR- 
TRAN IV Language, Form C28-6329. 

IBM 7040/7044 Operating System (16/32K): COBOL 
Language, Form C28-6336. 

The actual debugging languages themselves are 
based on cobol ( for cobol programs ) and Fortran iv 
(for Fortran iv and map programs). The map pro- 
grammer who is totally unfamiliar with Fortran should 
be able to use all the facilities described in this pub- 
lication with limited reference to the Fortran lan- 
guage publication listed above. 

The 7040/7044 (16/32K) Processor Debugging 
Package requires the same minimum machine con- 
figuration as the 7040/7044 ibjob Processor. The only 
difference lies in the use of the load-time facility, 
where the Debug Work Unit or the system checkpoint 
unit is required for the intermediate debugging output. 
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Introduction 



The problem of locating program errors rapidly and 
efficiently is of major concern to all computer users. 
The 7040/7044 (16/32K) Processor has been extended 
to include a debugging package as an aid in locating 
and correcting errors. To diagnose program errors, 
the programmer may wish to obtain information at key 
points in his program. The debugging package enables 
him to manipulate data, control processing, and print 
out the contents of program areas or machine registers. 
To use the debugging package, the programmer writes 
a debug request in the appropriate debugging lan- 
guage. Each request specifies what action to take and 
when to take such action. 

The debugging package provides two types of de- 
bugging: compile-time and load-time. Compile-time 
debugging is included with ibcbc at compilation to 
specify dumps at various points in a cobol source pro- 
gram. The text of the debug requests is similar to the 
cobol language. Load-time debugging uses the capa- 
bilities of ibmap and ibldr to provide debugging dur- 
ing the execution of a Fortran iv or map source 
program without recompiling or reassembling the pro- 
gram. The text of these debug requests is in a form 
similar to that of the Fortran iv language. 



In addition to the debugging package, the 7040/7044 
Operating System provides a dump program that can 
be used by object programs, system programs, or 
machine operators. This program lists the operator 
console panel, certain symbolic unit information, and 
specified portions of internal and external storage. It 
is not intended to replace object program symbolic 
debugging tools. 



Notation Conventions 

The following conventions apply to all card formats 
given in this publication: 

1. Brackets, [ ], indicate that the enclosed material 
may be omitted. 

2. Braces, ( ), indicate that the user must make a 
choice of the enclosed material. 

3. Upper-case words, if used, must be present in 
the form indicated. 

4. Lower-case words represent generic quantities 
whose values must be supplied by the user. 

The statement formats for cobol and Fortran iv 
adhere to the notation conventions given for each in 
their respective language publications. 
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Compile-Time Debugging for COBOL Programs 



The compile-time facility of the debugging package 
enables the cobol programmer to include debug re- 
quests with his source-language program. Debug re- 
quests are compiled with the source program and are 
executed at object time. The text of the requests is 
similar to the procedural text of cobol. In addition, 
a special count-conditional statement is provided. Since 
the procedural capabilities of the cobol compiler are 
available, a user can be highly selective in specifying 
what is to be dumped. He can manipulate and test the 
values of intermediate results in his program and 
dump only pertinent and meaningful information with- 
out affecting execution of the program itself. 

It is possible to delete the debug requests at load 
time without recompiling. The cobol programmer 
may, if desired, take advantage of the load-time 
facility, including the Additional Load-Time Debug- 
ging Features, and debug from an assembly listing of 
his program. 

Compile-Time Debugging Packet 

All compile-time requests for a given program are 
grouped together into a debugging packet and placed 
immediately after the scbend card of the associated 
source program. 

Compile-Time Debug Requests 

Each compile-time debug request is headed by a 
$ibdbc control card. The sibdbc card identifies indi- 
vidual requests and defines the point at which the 
request is to be executed. The $ibdbc card may contain 
any blanks desired for legibility except in a character 
string that is to be treated as a single parameter. The 
general form of this card is: 

1 8 16-72 

$IBDBC name location [, FATAL] [, DUMP = 

symbolic unit] [, MARKER = 
file-name] 

The parameters in the card are described as: 

name 

An optional user-assigned control-section name. Use of this 
parameter makes it possible to delete the request at load 
time. The name must be a unique control-section name 
consisting of at most six alphabetic or numeric characters. 
At least one of the characters must be alphabetic. 

location 

The COBOL section-name or paragraph-name (qualified, 
if necessary) indicating the point in the program at which 
the request is to be executed. Debug request statements 
are executed as if they were physically placed in the source 
programs following the section-name or paragraph-name 
specified, but preceding the text associated with that name. 

FATAL 

If FATAL is specified, severity codes normally assigned to 



errors in COBOL statements will also be generated for 
errors in debug request statements. If FATAL is not spec- 
ified and in the procedural text of a debug request an error 
is encountered that would normally be given a severity 
code of 2 or greater, the error message will be given a 
severity code of 1. An attempt will be made to interpret 
the statement; loading and execution of the object program 
will not be prevented. If interpretation is impossible, the 
erroneous statement will be discarded (but not the entire 
request, if it consists of more than one statement). 
Note that an error in location on an $IBDBC card or on an 
undefined symbol in the procedural statement of a debug 
request is always identified as a level 2 error, regardless 
of whether FATAL is specified. 

DUMP = symbolic unit 

This option indicates the unit on which the debugging 
output is to be written. The symbolic unit can be the sys- 
tem output unit, OU; or a utility unit, Uxx (where xx 
is 01, 02, ... 20). When this option is not specified, the 
debugging output will be written on the system output unit. 
The unit specified in the DUMP option must not be the 
same as an output unit used in the COBOL program. 

MARKER = file-name 

This option causes a dump indication record to be written 
on the output file specified by file-name each time a de- 
bugging display occurs at the location specified in this 
$IBDBC card, file-name is the name used in the FD entry 
to name the file. 

Dump indication records have the following format: 
***** DUMP NO. xxxxx WRITTEN ON u, c, nn ***** 

where: 

xxxxx is n when the nth debugging display is being executed, 
u is the output medium designation such as. T for tape 

or M for disk/drum modules, 
c is the channel to which the output medium is attached, 

nn is the unit number. 

When the above options cannot fit between columns 
8 and 72 of the sibdbc card, this control card can be 
extended if the remaining options are inserted between 
columns 8 and 72 of subsequent cards. These extension 
cards must contain a hyphen in column 7, and columns 
1 through 6 must be blank. 

Note that the above options must appear on the 
sibdbc card in the order in which they are described. 

The text of the debug request follows immediately 
after the sibdbc card. The text may consist of any valid 
procedural statements conforming to the requirements 
of the cobol language and format and the count condi- 
tional statement described in the following text. 

A compile-time debug request is terminated by an- 
other sibdbc card or any other control card with a $ in 
column one. 

DISPLAY Verb 

When used for debugging, the cobol verb display is 
modified to write on the symbolic unit specified by the 
dump parameter on the sibdbc card or on the system 
output tape. 
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Count-Conditional Statement 

A count-conditional statement available only for use in 
debug requests allows the programmer to qualify the 
time at which a debugging action should be taken. The 
count-conditional statement has the same structure as 
the if statement in cobol (conditional, true option, 
false option) and may be used in the same manner; 
i.e., it may be nested within other count-conditional 
statements or if statements and may have other count- 
conditional statements or if statements nested within 
it. The general form of the count-conditional statement 
is: 

ON k [AND EVERY m] [UNTIL n] statement-1 

nELSE / n -] 

OTHERWISE (statements J 

The letters k, m, and n are positive integers. 

If and every ra is not specified, but until n is speci- 
fied, m is assumed to be 1. The until option means 
up to but not including the nth time. If neither and 
every m nor until n is specified, action will take place 
only the kth time. 

EXAMPLES 

ON 3 DISPLAY A. 

The third time the count-conditional statement is executed, 
A is displayed. No action is taken at any other time. 

ON 4 UNTIL 8 DISPLAY A. 

A is displayed on the fourth, fifth, sixth, and seventh times 
through the count-conditional statement. No action is taken 
at any other time. ( This example implies, and has the same 
effect as, the statement ON 4 AND EVERY 1 UNTIL 8 
DISPLAY A.) 

ON 5 AND EVERY 3 UNTIL 12 DISPLAY A. 

A is displayed on the fifth, eighth, and eleventh times 
through the count-conditional statement. No action is taken 
at any other time. 

ON 3 AND EVERY 2 DISPLAY A. 

A is displayed on the third, fifth, seventh, ninth, . . . times 
through the statement. On the first, second, fourth, sixth, 
. . . times, no action is taken. 

ON 2 AND EVERY 2 UNTIL 10 DISPLAY A ELSE 

DISPLAY B. 

A is displayed on the second, fourth, sixth, and eighth times 
through the statement. B is displayed at all other times. 

Compiler Limitations 

In debugging statements, the word on may not be 
used with the size error option as is normally permis- 
sible with arithmetic statements or with the depending 
option in the go to statement. 

When the name associated with an unconditional 
go to is referred to by a symbolic debugging request, 
the transfer point specified by the go to statement 
should not be changed by an alter statement. 

With a 16K Operating System whose nucleus can 
be reduced sufficiently, the user may include expo- 
nentiation in symbolic debug. However, if the nucleus 
cannot be reduced sufficiently, he will not be able to 



use exponentiation in his cobol debug requests. (A 
32K user can always include exponentiation in his 
cobol debug requests.) 

Deleting Debug Requests 

Any debug request may be deleted by using the 
somit card. Its form is: 

1 8 16-72 

$OMIT name 

On the card, name is the control-section name of 
the request to be deleted. When used, somit cards are 
placed after the $ibjob card for the processor applica- 
tion and before the source deck or relocatable binary 
deck of the program involved. 



Example of a Compile-Time Debugging Packet 

Figure 1 gives an example of a compile-time debugging 
packet. The numbers in the first line across indicate 
the card columns in which the various fields begin. 

In the first request, on the first, fourth, and seventh 
times that control passes through point A in the pro- 
gram, Z is displayed (in its own format as defined in 
the source program) with the identifying heading, Z = . 

In the second request, the value of T ( with the iden- 
tifying heading, T=) is displayed and its value re- 
places the value of S at the point in the program 
identified as B of C. Further, if S is unequal to T, S is 
also displayed. This request may be deleted at any 
time through the use of a $omit card with the follow- 
ing form: 

1 8 16-72 

$OMIT NAME 

Execution of the third request causes both the mes- 
sage, v out of range, v=, and the value of V to be 
displayed the first nine times that V is greater than 
vmax when program control passes through point D. 
On the tenth time the request causes stop run to be 
executed. The fatal option on the sibdbc card head- 
ing this request inhibits execution of the source pro- 
gram if the compiler encounters an error. 



1 8 12 16 

SIBDBC A 

ON 1 AND EVERY 3 UNTIL 8 DISPLAY 

•Z='Z. 
SIBDBC NAME B OF C 

IF S NOT EQUAL TO T DISPLAY 'S-'S. 

MOVE T TO S. DISPLAY 'T-«T. 
SIBDBC D» FATAL 

IF V GREATER THAN VMAX ON 1 UNTIL 

10 DISPLAY »V OUT OF RANGE. V-«V 

ELSE STOP RUN. 



Figure 1. Example of a Compile-Time Debugging Packet 
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Load-Time Debugging for FORTRAN IV and MAP Programs 



The load-time facility of the debugging package en- 
ables Fortran iv and map programmers to include 
debug requests at load time to be executed with the 
object program, map object programs can be those gen- 
erated by ibftc and ibcbc as well as those written in 
map itself. The cobol programmer may, if desired, 
take advantage of the load-time facility and debug 
from an assembly listing of his program. The cobol 
programmer may use load-time debugging features 
while compile-time debug requests are still in his pro- 
gram. He may also use load-time debugging features 
at the same time he is using a $omit card to delete a 
debugging request. The Fortran iv programmer may 
also use the load-time facility at the map level. 

The debugging package, which consists of three 
main parts, is another processor application under 
ibjob. Following are the three parts: 

1. The first is a preprocessor used to compile all 
debug requests and to associate these requests with 
programs to be debugged. 

2. The second is an executable debugging program 
that is in core storage with the object program to be 
debugged and that performs necessary debugging. 

3. The third is a postprocessor that processes all 
dumps produced during program execution and causes 
those dumps to be written in the proper format. 

The debugging language used with the load-time 
facility is derived from the Fortran iv language. The 
statements available permit the programmer a high 
degree of flexibility in obtaining meaningful data. It 
is possible to perform arithmetic operations with object 
time values, to test results, and to freeze program ac- 
tion at a specified point and then dump selected infor- 
mation. In addition, the user can refer to symbols 
appearing in the source program by selecting the ap- 
propriate debugging dictionary option on the sibftc 
and sibmap control cards. (For additional information, 
see the section entitled "Debugging Dictionary.") 



load-Time Debugging Packet 

All load-time debug requests for a particular job run 
(any configuration of Fortran, cobol, or map source 
and/or binary decks) are grouped into a debugging 
packet headed by a sibdbl card and terminated by a 
sdend card. The load-time debugging packet is placed 
in the job deck following any source decks. The de- 
bugging packet may be placed either before or after 



the binary decks of the job run. The packet may be 
followed only by the following cards: sentry, slink, 
$endch, mbrel, and binary decks. 

The program stacking option on the $ibjob card must 
be source. 

$IBDBL Ccird 

The general form of the sibdbl card is : 
1 8 16-72 

$IBDBL [TRAP MAX = nd [.LINE 

MAX = n 2 ] [, Dump Marker 
Option] [, Debugging Work 
Unit Option] 

Columns 16-72, which are scanned in full, may con- 
tain any blanks desired for legibility, except in a char- 
acter string that is to be treated as a single symbol or 
constant. Note that in the options trap MAX = n x and 
line MAX = n 2 the user may, if he desires, separate the 
equal sign with blanks. 

The letters n L and n 2 are integers that should fall 
within the range 1 to 32767 decimal. 

The contents of the variable field, which control the 
debugging output and may be used in any order are: 

TRAP MAX = n t 

This specification causes termination of all debugging 
action after n t requests have been executed. If this 
option is omitted, the system assembly parameter for 
trap max, assembled as 30,000 decimal, will be used. 
line max = n 2 

The postprocessor will print no more than n 2 lines of 
output, excluding postmortem dumps. If this option is 
omitted, the system assembly parameter for line max, 
assembled as 1000 decimal, will be used. 

Dump Marker Option 

FORTRAN 
TOBOU 
JOBOUL 
IOBS = file-name 
_ \IOOP = unitl 

This option specifies the iocs level that the debug- 
ging routines will use to write dump markers each 
time a debug dump is taken. The iocs level specified 
should be the same as that used by the object program 
so that the dump markers will be synchronized with 
object program output. These markers will match the 
dump numbers written with the debug dumps after 
the object program is executed. If the dump marker 
option is not taken, no marker will be written. 
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If Fortran is specified, the object program uses the 
Fortran input/output subroutines, and markers are 
written on Fortran logical unit 6 in bcd mode using 
the Fortran input/output subroutines. 

If jobou or joboul is specified, the object program 
uses the Output Editor. 

If iobs= file-name is specified, the object program 
uses the iobs level of iocs. The name associated with 
the output file is file-name. Markers will be written on 
this file according to the mode and record type defined 
in the file control block. Note that no marker will be 
written if the file is not open, or if the logical record 
length of a Type 1 file or the block size of any file is 
less than the necessary six words that indicate the 
length of the dump marker. Only one file may be speci- 
fied for dump marking. 

If ioop= unitl is specified, the ioop level of iocs is 
used by the object program, unitl is a system output 
unit (OU), a system utility unit (U00-U99), or an 
intersystem reservation unit (101-120). Only one unit 
may be specified for dump marking. 

Debug Work Unit Option 

[,DWU=unit2] 

This option specifies the work unit for intermediate 
debugging output. unit2 is any unit designation that 
would be valid on the $file card, except the following: 
none, *, lbi, LB2, in, ou, pp, or card equipment. (For 
information on the $file card, see IBM 7040/7044 
Operating System (16/32K): Programmers Guide, 
Form C28-6318. ) If this option is not taken, the debug 
work unit is assumed to be the system checkpoint unit 
(cki). The assumed debug work unit is set by the 
$file card used when editing the debug preprocessor 
onto the system tape. 

Note: Debug work unit and dump marker unit 
specifications are processed following the assignment 
of ibjob work units, and prior to ibldr processing of 
unit designations on sfile cards and from file pseudo- 
operations. If the programmer wishes to assign the 
debug work unit to a specific unit, he should assign an 
intersystem reservation code to that unit on the ibsys 
level or otherwise insure that ibjob will not assign that 
unit as one of the system work units. 

$DEND Card 

The $dend card terminates the load-time debugging 
packet. The card format is: 

1 8 16-72 

$DEND 

Load-Time Debug Requests 

Each load-time debug request is headed by a $debug 
card, which identifies individual requests and specifies 



the point in the program at which the request is to be 
executed. There may be multiple requests per deck. 
The general form of the $debug card is: 



$DEBUG 



8 16-72 

deckname location 1 [, location2...] 



The variable field (columns 16-72) is scanned in full 
and, therefore, may contain any blanks desired for 
legibility, except in a character string that is to be 



legibility, except in a ^naia^ici auiug mat is ^ u^ 
igle symbol or integer. The parameters 



treated as a sin _,_ 

of the $debug card are 



deckname 

The name of the object deck to which this debug request 
applies. If this field is blank, the deck name specified on 
a preceding $DEBUG or $REDEF card will be assumed. 
If no deck name was specified, the request will be deleted. 

Symbols in the request that follows are considered 
to be in this deck. 

location 1... 

The location(s) of the executable instruction ( s ) at which 
this debug request is to be inserted. A location may be 
specified in any of the following ways: 

1. A statement number of an executable statement 
(FORTRAN IV only. See Appendix B, Restriction 6) 

2. A symbol 

3. A symbol ± an unsigned decimal integer 

4. The characters =R followed by an unsigned octal in- 
teger for a relative location (i.e., relative to the load ad- 
dress of the deck) 

5. The characters =A followed by an unsigned octal in- 
teger for an absolute location 

The debug request will be executed as if it had been 
physically inserted in the deck at the location(s) speci- 
fied. Debug request action occurs before the execution 
of the statement or instruction at the location. The 
locations at which debugging is specified will be modi- 
fied to provide a transfer (str instruction) to the de- 
bugging supervisor. Bits 1-11 will be set to zero and 
should not be changed by the object program. The 
transfer to the debugging supervisor is executed each 
time this location is reached, although conditional 
statements may cause action within the debug request 
to be skipped. The original instruction is always exe- 
cuted before the debug supervisor returns to the object 
program. 

The text of the request itself follows immediately 
after the $debug card. If an invalid or erroneous action 
is specified in the text of a debug request, that action is 
deleted. The text consists of procedural statements 
written in the Fortran format. , 

Extending the Variable Field of a Card 

The variable field of $ibdbl and sdebug control cards 
may be extended over more than one card by following 
the card with $etc cards as shown below. 



1 
$ETC 



8 



16-72 

Extension of variable field 
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Columns 16-72 are scanned in the same manner as 
the card preceding the $etc card. 



Debugging Statements 

The statements used in the text of a request are de- 
rived from the Fortran iv language, with additions 
and changes made for debugging purposes. Constants, 
variables, subscripts, arithmetic expressions, and logi- 
cal expressions that may be used within a debug state- 
ment are similar to those used by the Fortran iv pro- 
grammer. 

The debugging restrictions and modifications to 
standard Fortran iv usages are listed below. 

1. The debugging compiler treats blanks in a state- 
ment as terminators. Therefore, no blanks may be im- 
bedded in a character string that is to be treated as a 
single symbol, constant, operator, or verb. This re- 
striction also applies to debug elements preceded by 
the character = . 

2. At least one blank must follow each statement 
verb (for example, dumpdx, where b represents a 
blank). 

3. The operator ** (exponentiation) cannot be used 
in debug statements. 

4. Functions cannot appear in debug statements. 

5. The logical constants .true, and .false, cannot 
be used. 

6. A numerical constant may be represented as a 
real constant, a decimal integer constant, or an octal 
integer constant. A real constant is indicated by the in- 
clusion of a decimal point, or by the inclusion of the 
decimal point and the letters E, EE, or D, followed by 
an exponent. (E indicates single precision, EE and D 
double precision.) Octal integer constants are differ- 
entiated from decimal integer constants as follows: if 
the first digit of the number is zero and if the number 
does not contain any non-octal characters (8 or 9), it 
will be considered octal, and it may be up to 13 digits 
in length; otherwise it will be considered a decimal 
constant. Complex constants are of the form (ni, n 2 ), 
where n, represents the real part of the complex num- 
ber and n 2 the imaginary part. However, unlike the 
Fortran iv representation of a complex constant, n t 
and n 2 may be octal integers, decimal integers, or real 
constants. 

The following are examples of numerical constants: 



0123 

123 

0129 

0.129E3 

(0120,-129) 



Octal Integer 
Decimal Integer 
Decimal Integer 
Real 
Complex 



7. A variable name may be any legal map symbol. 
However, Fortran iv conventions will override map 
notation, and those map symbols (1.2) that would be 



treated as numerical constants (as on the right hand 
side of the equal sign in set statements) should be 
redefined prior to use. (See the explanation of the 
sredef card for details on the redefining facility.) The 
mode of a variable is indicated in a debugging dic- 
tionary or name statement rather than, as in Fortran 
iv, by its leading character or by the use of a Fortran 
iv Type statement. 

8. Subscripts may be any valid arithmetic expres- 
sions. Nonintegral subscripts will be truncated to in- 
teger values. 

9. =An and =Rn, where n is an unsigned octal 
integer, may be used as elements of expressions. The 
mode of these elements is octal. (See the "list State- 
ment" for a further description of the quantities =An 
and =Rn.) 

10. Elements of expressions may be preceded by 
deck name qualifiers of the form: 

deckname $ $element 
(See description under "Qualification of list Items.") 

11. Additional items that may be used as elements 
of expressions are described in Table 1, in the section 
"Quantities Available for Use in Debug Request State- 
ments." For full information on expressions, see the 
following section. 

Debug statements are punched in columns 7-72 of 
the card. Continuation cards are indicated by any 
character other than a blank or zero in column 6. Com- 
ments cards ( those with a C punched in column 1 ) are 
permitted. 

Arithmetic and Logical Expressions in Debugging 
Statements 

Arithmetic and logical expressions used in debugging 
statements are modified forms of the Fortran iv lan- 
guage. 

Arithmetic Expressions 

An arithmetic expression consists of sequences of con- 
stants, subscripted variables, and nonsubscripted vari- 
ables, separated by arithmetic operation symbols, 
commas, parentheses, and various special elements. 

The arithmetic operation symbols + — * / denote 
addition, subtraction, multiplication, and division, re- 
spectively. 

Quantities in arithmetic expressions need not be in 
the same mode. The hierarchy of modes is as follows: 

1. Complex 

2. Double precision real 

3. Real 

4. Octal and decimal integer 

Where modes are mixed, the quantities in the expres- 
sion will be converted to the mode used in the expres- 
sion that is highest in the hierarchy of modes. 
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Note that if octal integer, decimal integer, symbolic, 
logical, and/or alphameric modes are specified in 
arithmetic expressions no conversion will be per- 
formed, since these modes are equally low in the hier- 
archy. 

Logical Expressions 

A logical expression consists of sequences of logical 
variables, which must be separated by logical opera- 
tion symbols, and arithmetic expressions, which must 
be separated by relational operation symbols. A logical 
expression always has the value true or false. 

The permissible logical operators (where b repre- 
sents a blank and x and y are logical expressions) are: 



bNOTbx 


or 


b.NOT.bx 


xbANDby 


or 


xb.AND.by 


xbORby 


or 


xb.OR.by 



The operands can be relational expressions or logical 
variables. A logical variable is true if its sign is minus, 
false if its sign is plus. 

The permissible relational operators are: 



bGTb or b.GT.b 

bGEb or b.GE.b 

bLTb or b.LT.b 

bLEb or b.LE.b 

bEQb or b.EQ.b 

bNEb or b.NE.b 

bLGTb or b.LGT.b 

bLGEb or b.LGE.b 

bLLTb or b.LLT.b 

bLLEb or b.LLE.b 

bLEQb or b.LEQ.b 

bLNEb or b.LNE.b 



Greater than 

Greater than or equal to 

Less than 

Less than or equal to 

Equal to 

Not equal to 

Logically greater than 

Logically greater than or 

equal to 

Logically less than 

Logically less than or equal to 

Logically equal to 

Logically not equal to 



The operands can be numerical variables or expres- 
sions. 

The first six of the above relational operators result 
in an algebraic comparison between the operands. If 
they differ in mode type, the conversion is made as de- 
scribed for arithmetic expressions. If the operands are 
complex (e.g., (n b n 2 ) represents one operand and 
(n 3 , n 4 ) represents the other), they are considered 
equal only if ni=n 3 and n 2 = n 4 . The values ni 2 + n 2 2 
and n 3 2 +n 4 2 are used to determine which operand is 
greater. 

The last six of the above relational operators result 
in a 36 bit unsigned comparison. If the modes are 
mixed, no conversion is performed. 

Parentheses can be used in arithmetic or logical 
expressions to specify the order in which the opera- 
tions are to be performed. Where parentheses are 
omitted, the order of operations is as follows: 

*and/ 

+ and — 

relational operations 

NOT 

AND 

OR 
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SET (Arithmetic) Statement 

The set statement provides the programmer with 
arithmetic and logical capabilities within a debug re 
quest. The general form of this statement is : 

SET s 

The letter s is any valid arithmetic or logical state 
ment other than the logical if statement. 

EXAMPLES 

SET A=0 

SET B = C .GT. 4 (B is true if C is greater than 4; B is false 
otherwise ) 

Logical IF Statement 

The debugging logical if statement is similar to that of 
Fortran iv, with certain additions and restrictions. The 
general form of this statement is: 

IF (t) s 

or 
IFbtbs 

The letter b represents one or more blanks; t, any 
logical expression that contains neither function calls 
nor the ** operator; and s, an unconditional executable 
statement or an on statement followed by an uncon- 
ditional executable statement. 

If the logical expression t is true, statement s is exe- 
cuted. If t is false, statement s will not be executed. 

EXAMPLES 

IF (B EQ A * 3.5) DUMP X, Y, Z 
IF A(I, I- J) EQ 3.4E2*QSUM DUMP X 
| IF (X .EQ. 3 .AND. Z .LT. 24) GO TO 3 
IF LOGVAR .AND. (ALPHA + 6 LE BETA OR LGVAR1) 
RETURN 

ON Statement 

The on statement is a count-conditional statement that 
permits the programmer to control the time when a 
debugging action is to be taken. It is similar to the 
Fortran iv logical if statement and is of the general 
form: 

ON [(c)] i, j,ks 

The letters i, /', and k are any arithmetic expressions 
( if they are not integral, they will be truncated ) ; c is 
a unique symbol representing a counter name, which 
should not be contained in the debugging dictionary; 
and s is an unconditional executable statement or an 
if statement followed by an unconditional executable 
statement. 

Statement s is executed the ith time through the on 
statement and each kth time thereafter until / is ex- 
ceeded. If / is omitted, the statement is executed the 
ith time and every kth time thereafter. If k is omitted, 
it is assumed to be one. If both / and k are omitted, the 
statement is executed only the ith time through the 
on statement. 
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When included, c creates a named counter for the 
on statement. The value of c is initially zero; during 
execution of the on statement, the counter is in- 
cremented by one before being tested. As with other 
variables, c may be used in any computation or test, 
and it may be named in other on statements. 

If c is named in other on statements, c is incremented 
by one each time any one of the on statements is exe- 
cuted. The counter can appear on the left-hand side 
of an expression in a set statement. The deck name on 
the $debug card heading the request implicitly quali- 
fies c. All references to c that are implicitly or explicitly 
qualified by this deck name are treated as references 
to the counter created by c. Therefore, if c is dupli- 
cated by a symbol in an object deck's debugging dic- 
tionary, it will not be possible to refer to that object 
deck's symbol in the subsequent statement of the de- 
bugging packet. 

If c is not specified, an unnamed counter is created 
internally; it cannot be referred to by any other state- 
ment. 

GO TO Statement 

The statement go to n ( where n is a decimal integer ) 
is an unconditional transfer to the debugging state- 
ment numbered n. Statement numbers used in an un- 
conditional go to must refer to statements within the 
debugging packet, not to statement numbers in the 
program being debugged. 

LIST Statement 

The list statement specifies the storage areas and/or 
registers that are to be dumped. Its general form is: 

statement number LIST element 1, element2.... 

statement number is a standard Fortran statement 
number of up to five numeric characters (punched in 
columns 1-5) and element denotes the address of a 
quantity to be dumped. Any number of elements, sep- 
arated by commas, may be specified. 

The mode in which the data is dumped is deter- 
mined from the debugging dictionary, or from a name 
statement. If this information is not available, the 
dumps will be octal unless the mode is specified as 
in item 2 in the following text. 

Except where otherwise indicated "symbol" in the 
following items is defined either in the debugging dic- 
tionary or in a name statement. 

Elements may be specified in seven ways: 

1. Quantity — the specified quantity is dumped. It 
may be one of the following: 

symbol 

The array, double-precision number, complex number, or 
single word denoted by this symbol is dumped. 



symbol (subscripts) 

The array element, double-precision number, complex num- 
ber, or single word denoted by this subscripted symbol is 
dumped. Any symbol may be singly subscripted, but only 
those symbols that have had dimensions specified may have 
more than one subscript. The subscripts may be any arith- 
metic expressions. The mode of the dump is the same as 
the mode of the symbol. If ALPHA(6) is specified, the 
contents of the location ALPHA + 5 are dumped; however, 
if ALPHA is double-precision or complex, ALPHA +10 
and ALPHA + 11 are dumped. 

symbol ± n 

This causes the single word denoted by this quantity to 
be dumped, symbol is as defined in the preceding text and 
n is an unsigned decimal integer. The mode of the dump 
is that of the specified location and is not necessarily the 
same mode as the symbol. 



= Rn 



The word at relative location n where n is an unsigned 
octal integer, is dumped. Only one word is dumped, even 
though it may be part of a double-precision or a complex 
number. 

=An 

The word at absolute location n where n is an unsigned 
octal integer, is dumped. Only one word is dumped, even 
though it may be part of a double-precision or a complex 
number. 

The map programmer may refer to the sections 
"Quantities Available for Use in the Debug Request 
Statements" and "Item Designations for list State- 
ments" for additional ways of addressing quantities. 

2. (loci, loc2 [,m]) —this specification causes the 
region from loci through loc2 to be dumped in format 
m. loci and loc2 may be any of the quantities defined 
above, or a Fortran statement number within the 
source program. The permissible values of m are: 

O Octal 

S Symbolic instruction 

F Floating-point number 

X Fixed-point number 

D Double-precision number 

J Complex number 

L Logical 

H Alphameric 

If m is specified, it overrides any other mode desig- 
nations for the quantities involved. If m is not speci- 
fied, the region is dumped in the mode(s) of each item 
in the region, as defined in the debugging dictionary. 

Thus, if loc3 is a double-precision array and LOC4 
is a floating-point array with dimensions of (3, 10), the 
specification (loc3(6), loc4(3,4), f) causes loc3 + io 
through loc4 + h to be dumped in the floating-point 
mode. A specification of (6, = R127) causes the region 
from statement number 6 through relative location 127 
(octal) to be dumped in the mode(s) supplied by the 
debugging dictionary. A specification of (arrayi, 
arrays, x) causes all of arrayi, all intervening loca- 
tions, if any, and all of array2 to be dumped in the 
fixed-point decimal mode. 
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3. ( data list ) — selected elements of arrays are 
dumped. This specification operates in a manner sim- 
ilar to the implied do in Fortran iv input/output lists. 

data list may be one of the following: 



symbol (subscripts) 
( data list, range ) 
data list, data list... 



e.g., (A(I),I = 1,4) 
e.g.,((B(I,J), 1 = 1,4), J=l,3) 
e.g., (A(I),(C(J,I),J = 1,9,2), 
D(I), 1 = 1,4) 



Any arithmetic expression may be used as a sub- 
script. If it is not integral, it will be truncated. 

range has the following form: 

v = ai, a 2 [, a 8 ] 

The letter v is a subscript in this statement and the 
a t are arithmetic expressions. Any other use of v in the 
program or in the debugging packet will be ignored for 
this statement. The dumps specified by the data list are 
taken for v = a! through v = a 2 in increments of a 3 . If 
a 3 is omitted, it is assumed to be I. Ranges may be 
nested to a maximum subscript depth of three. 

The following are valid examples: 

(A(I,I),I = 1,3) 
dumps A( 1,1 ),A(2,2),A(3,3) 
(B(I,6-I),I=1,5,2) 
dumps B(l, 5), B(3,3), B(5, 1) 
((A(IJU = 1,3),J = 6,8,2) 

dumps A( 1, 6), A(2, 6), A(3, 6), A( 1, 8), A(2, 8), A(3, 8) 
( (C(2*J-4, 10-3*), 1=1, 3) J=3, 4) 
dumps C(2, 7), C(2, 4), C(2, 1), C(4, 7), C(4, 4), C(4, 1) 
(A( J, J), (C(2*J-4, 10-3*1), 1 = 1, 3), J = 3, 4) 
dumps A(3, 3), C(2, 7), C(2, 4), C(2, 1), A(4, 4), C(4,7), 
C(4,4),C(4, 1) 

Because the following example contains four nested 
ranges, it is invalid: 

((((A(I,J,K),B(I,J,L),I = 1,2),J = 1,2),K = 1,2), 
L = l,2) 

The statement list ( a ( i, j ) , i = i, a: ) specifies a ( l, j ) , 
a (2, j), and a (3, j), where J is a variable defined pre- 
viously either in the source program or in the de- 
bugging packet. 

4. // or /control-section name/ — blank common or 
the specified control section is dumped. If the /control- 
section name/ option is specified, the debug pre- 
processor uses the following as the length of the con- 
trol section: the length of the first real section of the 
name encountered, even if $name, $use, or $omit cards 
cause this section to be deleted in favor of another of 
different length at object time. 

5. //±n or /control-section name/±n — the word 
that is dumped is at the beginning of blank common 
± n or at the beginning of the specified control section 
±n, where n is an integer. Fortran labeled common 
names are considered control-section names. 

6. program — the entire object program and all sys- 



tem subroutines used by the object program, as well 
as file text, buffers, and blank common, are dumped. 

7. 'message' — a message is printed as specified. The 
message itself should not exceed the number of char- 
acters allowable for a single printed line. It cannot con 
tain quotation marks. The external quotation marks, 
however, are required. Two quotation marks will yield 
a blank line. 

8. console — the contents of the ac, mq, index regis 
ters, entry keys, sense switches, divide check, and over 
flow indicators are dumped. 

Additional list items are described in Table 1, in the 
section "Quantities Available for Use in Debug Re- 
quest Statements." 

Qualifications of LIST Items 

Unless explicitly qualified, all symbols in a debug re- 
quest are implicitly qualified by the deck name of the 
$debug card heading the request. 

To allow for communication between decks, any 
item or set of items may be qualified with the deck 
name and two dollar signs, as shown: 

deckname$$item 
deckname$$ ( item, item,..) 

The items specified are as defined for list elements 
For example, a$$b refers to symbol B in deck A, and 
ab$$(bb, cb, (rb, sb, o) ) refers to items bb, cb, and the 
octal region rb through sb, which are all in deck ab. 

DUMP Statement 

The dump statement dumps the quantities to be printed 
as debugging output. It is similar in structure to the 
Fortran iv write statement and is of the general form ; 

DUMP list 

list is a series of items that is either a direct refer 
ence to the data to be dumped or the statement num 
ber(s) of list statements specifying the data to be 
dumped. The acceptable data specifications for both 
direct references and list statements are itemized in 
the discussion of the list statement. 

The dump statement causes information to be written 
on the debug work unit (dwu). The postprocessor 
edits the data on the dwu and writes it and the dump 
number on the system output unit. The formats sup 
plied for the list items of the dump statements are: 

1. The symbolic reference of the item, along with 
its location(s), deck name, and control section, is 
written to identify the debugging output. ( The relative 
location may not agree with that of the map assembly 
because of the deletion of control sections and adjust- 
ment caused by the use of the even pseudo-operation. ) 

2. The value(s) of the item is written. The format, 
which is based on the number of elements in the item 
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and the mode of the item 
the section "list Statement' 



(as listed under point 2 in 
'), is derived as follows: 



TYPE 


no. /line 


FOBMAT 


Octal 


4 


OP XXXXXX XXXXXX 


Symbolic 






Instruction 


2 


±x xxxxx x xxxxx OP A, T, D 1 . 


Floating- 






Point 


6 


±.xxxxxxxx±xx 


Fixed-Point 


6 


± xxxxxxxxxxxx. (leading 
zeros dropped) 


Double- 






Precision 


4 


± .xxxxxxxxxxxxxxxxD ± XX 


Complex 


3 


± .XXXXXXXX ± XX ± .xxxxxxxx ± xxj 


Logical 


8 


.TRUE, or .FALSE. 


Alphameric 


96 char 


XXXX...XXX 



CALL Statement 

The call statement is used to call subroutines. Its gen- 
eral forms are: 

CALL subr 

CALL subr (argl, arg2,...) 

where subr is the name of the subroutine being called 
and argl, arg2, . . . are the arguments. The subroutine 
that has been called must use neither the chain facili- 
ties of ibjob nor call s.sldr; otherwise, overlay might 
be induced, subr must be a real section name. The 
subroutine must be in one of the input decks if the 
job is a chain job. Otherwise it may be loaded from 
iblib. Output arguments to a subroutine that has been 
called may not be constants, any of the quantities listed 
in Table 1, or quantities that involve address computa- 
tion. 

RETURN Statement 

The return statement causes a return to the inter- 
rupted program. There is an implicit return at the 
end of each debug request. 

PAUSE Statement 

This statement causes the message "debug request 
pause" to be printed, and processing to be suspended. 
When start is pressed, execution continues with the 
next statement in the request. 

STOP and CALL EXIT Statements 

The stop and call exit statements terminate execu- 
tion by transferring to s.pciT. 

NAME Statement 

The name statement permits the programmer to define 
symbols for use within debug requests. It also defines 
symbols where no debugging dictionary, or an insuf- 
ficient one, has been supplied. 

iOP A, T, D refers to the symbolic representation of a machine language 
instruction. This is primarily of interest to the MAP programmer. 



The general form of the name statement is: 

NAME symboli/ ■] _ jsjeyv f ( mode [ ( dimensions ) ] ) 

[, symbol 2 /..] 
The parameters are: 

symboli 

Any valid MAP symbol. 

location 

A location designation. It may be a nonsubscripted symbol 
(plus or minus an integer, if desired); = Rn (relative 
location), where n is an unsigned octal integer; or =An 
(absolute location) where n is an unsigned octal integer. 

= NEW 

A location of octal format or an area corresponding to the 
specified mode and dimensions is to be generated for the 
symbol. 

( mode ) 

The mode of symbol. It may be O, F, X, D, J, L, S, or H, 
as described in the discussion of the LIST statement. 

( dimensions ) 

The dimensions, if any, of the array denoted by symbol 
are specified as: 

(di, d 3 , da) 

Arrays are structured and referred to exactly as they are 
in FORTRAN IV. 

The Fortran programmer will primarily use the 
= new option of the name statement. 

The deck name on the $debug card heading the 
debug request in which a name statement is found 
qualifies implicitly the symbol defined in the name 
statement. The name statement defines the symbol 
only for subsequent uses of that symbol (which has 
been implicitly or explicitly qualified by the deck 
name on the sdebug card ) . 

This ahjo applies to =new symbols. The same sym- 
bol may not appear more than once under the =new 
option; that is, the user should not use the =new 
option in more than one name statement for the same 
symbol. By the same token, he may not define the same 
symbol in name statements more than once for a single 
object deck. 



Redefining Symbols 

The 8Redef card allows the user to change the names 
of symbols used in source decks to make them accept- 
able for use in debug requests. Unacceptable symbols 
are those map symbols that would be interpreted as 
numbers by the debug compiler (e.g., 0.1E3, 4.6EE2, 
633.D4, 1.2). The general form of the $redef card is: 

1 8 16-72 

$REDEF deckname oldibASbnewx 

[, oldabASbnewa . . .]. 

deckname is the name of the deck in which the sym- 
bol to be redefined appears; b represents one or more 
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blanks; the oldx are the symbols to be redefined; and 
the new x are the new names of the symbols. 

The variable field (columns 16-72) of a $redef card 
may be extended to more than one card by using the 
$etc card as described for the $debug card in the sec- 
tion "Load-Time Debug Requests." 

$redef must be followed immediately by a $debug 
card or another $redef card. 



Debugging Dictionary 

The debugging dictionary provides communication be- 
tween the program being debugged and the debugging 
package. This dictionary contains symbols, with their 
relative locations, modes, dimensions, and mode 
changes. It also contains Fortran statement numbers 
and their relative locations. 

The debugging dictionary is requested by the user 
on a $ibmap or $ibftc control card and, when re- 
quested, is produced by ibmap. The general form of 
the control card is: 



8 



16-72 



UlBMAPf 
I $IBFTC \ 



deckname other options 

[, debug dictionary options] 

The card name, deck name, and other options are as 
given in the publication IBM 7040/7044 Operating Sys- 
tem (16/32K): Programmer's Guide, Form C28-6318. 

The debugging dictionary options are: 

NODD 

No debugging dictionary. This is the standard option, which 
specifies that a debugging dictionary is not desired. If no 
option is specified, NODD will be assumed. 



DD 



Full debugging dictionary. All mode changes and symbols 
used in the MAP program will appear in the debugging 
dictionary. In a FORTRAN IV program, all statement num- 
bers, all variable names, and all symbols generated by 
IBFTC will be included. 

SDD 

Short debugging dictionary. Only those symbols specified 
by the MAP pseudo-operation KEEP (described in the 
section "KEEP Pseudo-Operation") will appear in the de- 
bugging dictionary. If this option is specified on a $IBFTC 
card, IBFTC will generate KEEP operations for statement 
numbers and program variable names. 

Supplying Modal Information to the Debugging 
Dictionary 

ibftc supplies modal and dimensional information to 
ibmap and then, automatically, to the debugging dic- 
tionary. When double-precision (D) or complex (J) 
modes are specified, the dimensions indicate the num- 
ber of two-word entries contained in the array. (The 
product of these numbers will equal half the value 
field of the bss. ) However, the map programmer must 
supply this information himself when it cannot be 



assumed by the nature of the instruction, i.e., when 
he is using bss, bes, equ, and syn. (Only modal in- 
formation may be given with a bes; dimensional data 
will be ignored. ) This information is specified in addi- 
tional subfields of the variable field of these opera- 
tions, as: 



NAME FIELD 

Symbol 



OPERATION 
FIELD 



VARIABLE FIELD 



/BSS } 

\ EQU ( Vame , mode [ ( di, d 2 , d 3 ) ] 

(SYN ) 
symbol and value are the standard forms for these 
pseudo-operations; mode is O, F, X, D, J, L, S, or H, 
as described in the discussion of the list statement; 
and d h d 2 , and d 3 are the dimensions, if any, of the 
array denoted by the symbol. (Arrays are structured 
and are referred to as in fobtban.) 



EXAMPLES 






A 


BSS 


25, F(5,5) 


B 


EQU 


A + 10, F(5, 3, 2 


C 


SYN 


A + 6,X 


D 


BES 


2, X 



KEEP Pseudo-Operation 

The keep pseudo-operation permits the map program 
mer to specify, in his source program, a debugging 
dictionary that contains only those symbols he wishes 
to use in debug requests. The format of the keep 
pseudo-operation is: 

OPERATION 
NAME FIELD FIELD VARIABLE FIELD 

Blanks KEEP One or more symbols separated 

by commas. 

The symbols in the variable field are entered into 
the debugging dictionary along with any modal and 
dimensional information that was supplied in bss, bes, 
equ, and syn pseudo-operations. Any number of keep 
pseudo-operations may appear in a program. If the 
nodd or dd option was specified on the $ibmap card, 
the keep pseudo-operation is ignored. 

Note that qualified symbols are not entered into the 
debugging dictionary. The first encountered of the 
same named symbols is the one entered into the de- 
bugging dictionary. 

Additional Load-Time Debugging Features 

The following sections contain descriptions of addi- 
tional debugging facilities that are of interest mainly 
to the map programmer, but may also be used by the 
fobtran or cobol programmer. 

Quantities Available for Use in Debug Request 
Statements 

The quantities in Table 1 are available for use in state- 
ments that make up the text of a debug request. There 
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should not be a blank between the equal sign and the 
quantity. 

Table 1. Special Quantities Available for Use in Statements 



An effective address is of the form: 



QUANTITY 



DEFINITION 



= AC Accumulator ( S, 1, 2, . . . , 35 ) . 

= AC (ii — i 2 ) Accumulator bits ii, through i 2 ; 

O^ii ^i 2 ^35; bit 0=S-bit. 
= LAC Logical accumulator (P, 1, 2, . . . , 35). 

= LAC ( it — i 2 ) Logical accumulator bits it through i 2 ; 

O^ii ^i 2 ^35; bit 0=P-bit. 
= MQ Multiplier-quotient register (S, 1, 2, . . . 

= MQ (ii — i 2 ) Multiplier-quotient bits ii through i 2 ; 

O^k ^i 2 ^35; bit = S-bit. 
= XRn Index register n; 15=n ^7. 



35' 



Notes: 

1. The above quantities in arithmetic or logical expressions 
have the value of the registers upon entry to the debugging 
routines or the values subsequently assigned by their appear- 
ance on the left-hand side of a SET statement. The values of 
=XR3, =XR5, = XR6, and =XR7 are the logical OR's of index 
register 1, 2, and/or 4. Reference to these values does not auto- 
matically reset the index registers. 

If the above quantities (except =XR3, =XR5, =XR6, or 
= XR7) appear on the left-hand side of a SET statement, the 
register contains the newly assigned value when subsequently 
dumped or referred to in a DEBUG statement. The register will 
also contain this newly assigned value upon re-entry to the 
object program unless the register specified was =LAC, 
= LAC(ix-i 2 ), XR3, XR5, XR6, or XR7. Note that =LAC 
and =AC refer to separate locations in the /DEBUG deck; 
setting one does not affect the other. 

The mode of an index register quantity in a statement is in- 
teger (i.e., fixed-point). The other register quantities are of 
indeterminate mode; they are never converted and the values of 
other variables in the statement are not converted to agree with 
them. 

2. When the user specifies a bit extraction of AC, LAC, or 
MQ, the bits extracted will be right-justified and will be dumped 
under the heading /DEBUG +n (where n is a relative location). 

The following examples of the logical if clause illus- 
trate the use of some of the quantities that refer to 
internal registers. 

IF(=LACOR =MQ) 

IF (=XR4-8EQ3*=XR2) 

Address Computation 

Considered as a whole, an expression represents an 
effective address just as does any individual element. 
The effective address is determined through the chain- 
ing effect of a series of sequential steps, each step be- 
ing the effective address upon which the succeeding 
step is to operate. 



The form for an address expression is: 



= C ( effective address 



D ; 0- 
[| •!■■■] 



C ( effective address ) 



1 



I ADDR 
base address I KDECR 

L/(ii-i.) 



Hi 



COMPL 



] 



The base address may be any of the following: 

1. Any subscripted or nonsubscripted variable de- 
fined in the source deck, to which reference is cur- 
rently being made 

2. Any of the special names (=XRn, =ac, etc.) 
specified previously. These special names must be 
followed by one of the extraction options described 
below [i.e., addr, decr, or (ii-i2)] 

3. A relative ( =Rn) or an absolute ( =An) address 

4. A decimal integer 

5. A statement number ( Fortran only) 

6. Another effective address expression using any 
of the four items above as a base address and the 
operators described below 

Components of the operator string may be any of 
the following terms: 

OPERATOR DEFINITION 

ADDR Use, as the next effective address, the address 

portion of the word specified by the current 

effective address. 
DECR Same as above, using the decrement portion. 

(ii-i 2 ) Same as above, using bits ii through i 2 for 

O^ii ^i 2 ^35. 
COMPL Complement the current effective address to 

form the next effective address. 
+ argument Add the specified argument, which can be 

any of the forms defined for a base address, 

to the current effective address to form the 

next effective address. 
— argument Same as above, but subtract. 

* argument Same as above, but multiply. 

/ argument Same as above, but divide. 

The following are examples of address computation: 



= C(A) 

DUMP =C(A) 
SET=C(A)= =C(B)+2 
= C(A,ADDR) 

= C(A(5), DECR, COMPL, 

+ A(3)) 

= C(A(7), DECR, + =C(A(7), 
ADDR), -1) 



The address of A 
Same as DUMP A 
Same as SET A=B + 2 
The address portion of the 
word at location A 
The complement of the 
decrement portion of A ( 5 ) , 
plus A(3) 

The decrement portion of 
A(7) plus the address por- 
tion of A( 7 ) , minus one 



Bit Extraction 

In arithmetic expressions (e.g., in set, if, call, or on 
statements and also in address computation and in 
subscripts ) it is convenient to be able to handle partial 
word operations. The notation to be used is: 

= C (address computation) ( bit specification ) 

or 
= mr ( bit specification ) 
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where the bit specification is ii-i 2 , addr, or decr, and 
mr (machine register) is ac, lac, mq, or XRn; 

= mr (i) 

where 0;^i^35 is also permitted. 

The following are examples of partial word oper- 
ations: 



= C(A) (18-20) 
= AC(0) 
= MQ(17) 



The tag of A 

The sign of the AC 

Bit 17 of the MQ 



The following statement replaces the decrement of 
the word at A with the sum of 6 and the tag of B: 

SET=C(A) (DECK)= =C(B) (18-20) +6 

The following statement replaces the address por- 
tion of the ac with the address portion of the word 
at Q (the rest of the ac is not affected) if the mq 
bits 4 and 6 are 1, and bits 5 and 7 are 0: 

IF =MQ (4-7) EQ012SET=AC (ADDR) =Q 

The value of an item in an expression or output list 
on which bit extraction has been performed consists 
of those bits right-adjusted with zeros in the high- 
order positions. Note that the logical value of such 
an item is always false if the number of bits extracted 
is 35 or fewer. (Any type conversion necessary is done 
after the extraction.) 



Location Values 

When manipulating instructions, the map program- 
mer often needs the value of a symbol rather than the 
contents of the location addressed by the symbol. The 
programmer uses the notation =V (symbol) to desig- 
nate the value of a symbol. 

EXAMPLE 

SET =C(Q,ADDR)== =V(S) + 1 

This replaces the address field of Q with one plus 
the location value of S. 



Example of a Load-Time Debugging Packet 
Used with a FORTRAN IV Program 

Figure 2 contains an example of a load-time debugging 
packet for a Fortran iv program. The numbers in the 
first line across indicate the card columns in which the 
various fields begin. 

The $ibdbl card heading the packet calls in the de- 
bugging compiler. It specifies that all debugging ac- 
tivity is to cease when 450 debug requests have been 
executed at object time, that a maximum of 500 lines 
of debugging output is to be printed, that the Fortran 
Input/Output Subroutines are to be used to write 
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Figure 2. Symbolic Debugging — FORTRAN Example 
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Figure 3. Symbolic Debugging — MAP Example 

dump markers (on Fortran logical unit 6) and that 
utility unit 11 is to be used for the debugging work 
unit. 

The first debug request is executed immediately 
before statement 25 in deck main. The real variable 
A is defined for use in the debugging requests for that 
deck. The first time statement 25 is executed, A is 
set to 1.4. beta (in program main) is tested before 
each execution of statement 25. If beta is less than A, 
beta and the elements described by list statement 
number 5, contained in the third request, are dumped; 
the message beta too small is printed; and A is de- 
creased by 0.1. If beta is greater than or equal to A, 
return is made to the interrupted program; then state- 
ment 25 is executed. 

The second and fourth debug requests are executed 
at statements 1 and 30, respectively, in deck subr. 
Suppose that deck main calls subr several times and 
that statement 1 is the first executable statement in 
subr. Further, suppose that subr contains a do loop 
that causes statement 30 to be executed several times. 
Under these conditions, the second request sets the 
counter X to each time that subr is called; the fourth 
request dumps array arraya in program main, the 
first, fourth, seventh, etc., times that statement 30 in 
subr is executed; in addition, it dumps the principal 
diagonal of the matrix carray (in deck subr). Thus, 



the second and fourth requests trace the initial action 
of subr each time it is called. 

The third request is executed immediately before 
each execution of statement number 48 in main. The 
value of a-b*c is tested against 3.5*D, and if the two 
values are not equal, control returns to the program. 
If they are equal, the following are dumped: 

1. The area (in complex number format) from U 
through V (if V is an array, the entire array will be 
dumped ) . 

2. darray (1, 7, 3) and the message a-b*c eq 3.5*d 
caused program stop. Program execution then stops 
and the debug postprocessor is called. 

The third request also contains list statement num- 
ber 5, which, when used in a dump statement, causes 
the following information to be dumped: alpha (s, i), 

ALPHA (8, 2), ALPHA (9, l), ALPHA (9, 2), . . . , ALPHA 

(n, 2); all of the elements of barray; and all of blank 
common. 

The $dend card terminates the action of the debug- 
ging compiler. 

Example of a Load-Time Debugging Packet 
Used with a MAP Program 

Figure 3 illustrates a load-time debugging packet for 
a map program. The numbers in the first line across 
indicate the card columns in which the various fields 
begin. 
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The $ibdbl card heading the packet specifies that all 
debugging activity is to cease when 1,000 requests 
have been executed and that a maximum of 500 lines 
of debugging output is to be printed. It also specifies 
that the object program is using the Output Editor 
(joboul) and that the Debugging Work Unit is as- 
sumed to be the system checkpoint unit. 

The first request specifies that the elements in list 
statement numbers 2 and 3 ( which appear later in the 
packet ) are to be dumped the first time and each time 
thereafter up to but not including the eleventh time 
that the instruction at B4 in decka is to be executed. 

The second request is executed immediately preced- 
ing each execution of the instruction at start +7 in 
deckb. On the third, sixth, ninth, twelfth, fifteenth, and 
eighteenth times that logical variable logvar is true 
(i.e., sign is nonzero), the following will be dumped: 
X; control section cntra; and the region from relative 
locations 6 (octal) through 103 (octal) in octal for- 
mat. The second request also contains list statement 
3, which, when used in a dump statement, causes the 
quantity quan and the blank common (//) control 
section to be dumped. 



On the hundredth time that location B4 in decka 
is reached, information specified by the third request 
is dumped, program execution is terminated, and the 
debug postprocessor is called. At all other times, con 
trol is returned to the interrupted program. The infor 
mation dumped consists of the status of the console 
registers (list statement number 2), and the elements 
specified in list statement number 3, contained in the 
second request. 

The fourth request causes a test to be made the 
first time and every second time thereafter, until the 
ninth time that the instruction at restart in deckb is 
to be executed. It tests quan, and if quan is zero, the 
following are dumped: the elements in list statement 
number 2 (contained in the third request), the mes- 
sage quan equal to zero, and the elements in list 
statement number 6 (which specifies the region from 
restrt through restrt +99 in symbolic format). 

The fifth request is executed immediately before 
each execution of statements B7 and A4 in decka. If 
A is less than B, control is returned to the interrupted 
program; otherwise, A and B are dumped. 
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Dump Program 



The ibm 7040/7044 Operating System contains a gen- 
eral diagnostic and Dump program that provides error 
messages, error dumps, and debugging dumps during 
operation of the system. Assembled with this program 
is a series of dump parameters, identified by five-digit 
error numbers, that permits the system program to 
specify the error message and extent of the dump to 
be provided when a specific error condition occurs. 

The Dump program contains terminal diagnostic 
facilities for system programs, for machine conditions 
resulting in a trap under error conditions, and for 
Input/Output Control System error conditions for 
which no error return has been specified. When such 
a system error occurs, the console panels and a portion 
of core storage is saved, and the Dump program is 
loaded automatically to give a partial or full core 
storage dump and/or a selective dump of external 
storage. 

To preserve core storage space, all terminal error 
messages are carried in the Dump program rather than 
in the Nucleus or the Input/Output Control System. 

The Dump program appears in the System Library 
as four phases or core loads. When loaded, it overlays 
the higher levels of iocs. After the dump is finished, 
the combined monitors and a new iocs are brought in 
and control is released to the Supervisor, unless the 
return is specified. If the return is specified, core stor- 
age is restored. 



Calling Sequence 

An object program may relinquish control to the 
Dump routine in the Nucleus by means of the follow- 
ing calling sequence: 



SXA 
TSX 
pfx 
PZE 



• + 3,4 
S.SDMP,4 

rel,t,errno 

** 



( or the equivalent ] 



The prefix pfx is interpreted as follows: 

Sign Bit = 1 Pause before returning 

Bit 1 = 1 Dump system panel 

Bit 2 =1 Traceback 

s.sdmp is the entry point to the Dump routine in the 
Nucleus. The location ret,t is the point to which con- 
trol returns upon completion of the dump. The errno 
is a five-digit decimal number that is used to identify 
the series of parameters describing the error message 
desired, the special editing routines, and the portions 
of internal and external storage to be dumped. Upon 



completion of the dump, control is returned to the 
Supervisor, and processing resumes with the next $job 
card unless ret,t is non-zero. 

A means of obtaining a terminal core dump is to 
execute the following instructions: 



SXA 
TSX 
PZE 
PZE 



* + 3,4 

S.SDMP,4 

,,13000 



errno 13000 may be used to obtain a full core stor- 
age dump in octal with mnemonics and bcd. 

Format 

Depending upon the parameters assembled with the 
Dump program, a call to the Dump program results 
in one or more of the following types of output: 

1. On-line message on the console typewriter 

2. Off-line message on the system output unit 

3. A dump on the system output unit 

The dumps of the console panel and the system 
panel, the core storage dump, and the external storage 
dump on the system output unit may be obtained in- 
dividually or in any combination. The storage dumps 
may be given in any combination of the following five 
options : 

1. Octal dump (single line) 

2. bcd dump (single line) 

3. Octal dump with bcd (double line) 

4. Octal dump with mnemonics (double line) 

5. Octal dump with mnemonics and bcd (double 
line) 

On-Line Message 

The on-line message consists of a five-digit message 
number that is included in the calling sequence and of 
a briefly worded message. The phrase job terminated 
is appended by the Dump program if no return is 
provided. 

Off-line /Message 

The off-line message consists of the five-digit message 
number, the bcd contents of location s.scur, the bcd 
contents of location s.sfaz, the location of the tsx in- 
struction used in the calling sequence, and the com- 
plete error message provided in the dump parameters. 
This appears in the heading above the console dump. 

Dump Output 

An example of an octal dump with mnemonics and bcd 
characters is shown in Figure 4. 
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SYSTEM LIBRARY NAP FOR MANUAL 10000 DUMP OF IRSYS IBIOC 



ERROR LOCATICN 00103 

OPERATOR CALL TO DUMP 



JOB START 000000000000 



07/18/63 PACE 19 



TIME 00 MIN 00 SfC 



INDICATORS 




SENSE SWITCHES 






XRl 


XR2 


XR4 


CFL OCT 


I 


2 3 4 


5 


6 


00001 


000 14 


57625 


ON LFF 


CFF 


OFF OFF OFF 


OFF 


OFF 


-77777 


-77764 


-20153 


AC 




MQ 












0000001000001 




COOCOOOOOOOC 












TACHED DEVICFS 

















SYSTEM UNITS TABLF 



C 01135 00571 



C 01C35 00525 



DETACHED DEVICES 

S.SLB2 
S.SIN2 
S.S0U2 
S.SPP2 
S.SU07 
S.SU31 
S.SU32 
S.SU33 
S.SU34 
S.SU35 



042000000000 
HPR 4+0000 



00010 
00020 
00030 
00040 
00050 
00060 
00070 
00100 
00110 
00120 
00130 
00140 
00150 
00160 
00170 
00200 



002000000011 
TRA 0+0009 



000000000000 
000000 



000000000000 
000000 



002000004210 
TRA 0+OOK8 



076400002221 
BSR 7U00BA 



-053400100101 
LXC N10811 



002000000053 
TRA 0+000$ 



000020000000 
00+000 



076000000004 
ENK 7 0004 



-050000100135 
CAL N0081* 



002600640542 
TRCE 0F0U5K 



002000002235 
TRA 0+OOB* 



002000002651 
TRA O+OOFR 



002000010364 
TRA 0+013U 



002000010373 
TRA 0+013, 



012224010364 
1BD13U 



000016002126 
00«OAF 



-012141410011 
JAJJ09 



0C2C60000000 
TRA « 0+ OOC 



-16270C0C3C26 
TSL *GOOHF 



OCOCOOOOOOOO 
OOOOOC 



OOOCOCOCOCOO 
000000 



20000110C054 
TIX +C180* 



063400100064 
SXA 61080U 



OOOCOOOOOOOO 
OOOOOC 



052700002232 
XEC 5B00B+ 



-076300000044 
LGL PTCOOM 



077400100003 
AXT 7(0803 



-002400634541 
TRCC -DOTNJ 



002C0O40O0O2 
TRA 0+0-02 



OC2C0COC27O1 
TRA 0+00G1 



CC2000010372 
TRA 0+013= 



002CC0011731 
TRA 0+01*1 



000001010000 
001100 



OC0701100603 
71863 



0020CC004121 
TRA 0+COJA 



C000C10O356O 
0010* 



OOOOCCOOCCOO 
000000 



000010002725 
0080GE 



0C20CC004223 
TRA 0+OOKC 



0420C000C052 
HPR 4+000- 



05358O10C101 
LAC 5*0811 



000000000000 
COOOOO 



C634C0400105 
SXA 6)0-15 



0602COOOC054 
SLW 62C00* 



-162301100060 
SAC1 *C180 



0C24CC620541 
TRCC 0D0S5J 



C020C0002251 
TRA 0+OOBR 



0020CC002700 
TRA O+OOGO 



-1627C001C607 
TSL *GC167 



0020C0011656 
TRA 0+01** 



OC07C1734660 
071,0 



CC06C301U11 
Q63 199 



SYSTEM CONTROL BLOCK 



04 04 73 00327 

412000 05134 

000001000000 

00000 00000 



04 03 74 00331 

410000 07006 

000001000000 

00000 00000 



UNIT CONTROL BLOCK 



OOOOOOCOOOOO 
000000 



-162700003026 
TSL «GOOHF 



-162700C03026 
TSL «GO0HF 



-176000000014 
ICT * 000' 



000000000000 
000000 



077400100012 
AXT 7I08C0 



100001100064 
TXI 80180U 



000000000000 
000000 



007400400137 
TSX 0(0-1* 



040000000050 
ADD 400000. 



077100000006 
ARS 7Z0006 



-002200614540 
TRCB -BO/N- 



002000002065 
TRA 0+00+V 



002000002663 
TRA O+OOFT 



■162700010607 
TSL »G0167 



002000011650 
TRA 0+01«Q 



000000000001 
C00001 



000000000000 

PQOQQ Q 



002060000003 
TRA » 0+ 003 



000001003560 
0010* 



374521200000 
TXH *NA+00 



002000004154 
TRA O+OOJ* 



000000000000 
000000 



076200002221 
RDS 7S00BA 



050000100102 
CLA 500812 



000000000000 
000000 



223420000000 
TIX Bl+OOO 



060200000050 
SLW 62000Q 



-162300100060 
SACO *C080 



312245642360 
TXH IBNUC 



076000000161 
SWT 7 001/ 



002000002662 
TRA O+OOFS 



-162700010607 
TSL *G0167 



002000011667 
TRA 0+01*X 



000005002414 
0050D' 



000000000000 
000000 



000000000000 
000000 



-162700003026 
TSL *GO0HF 



000701050603 
071563 



000000000000 
000000 



000000000000 
000000 



-0 54000000101 
RCHB N-0011 



062100000101 
STA 6A0011 



000000000000 
000000 



000000057625 
0005»E 



-032000000117 
ANA L+001* 



077 1000Q0006 
ARS 7Z0006 



002000001407 
TRA 0+00' 7 



002000400001 
TRA 0+0-01 



002000400003 
TRA 0+0-03 



-162700010607 
TSL *G0167 



002000012001 
TRA 0+01+1 



000005002421 
0050DA 



000261077515 
_____ 02/7** 



0000 
000000 
4 00000 
00000 
00000 
00000 
00000 
00000 



02201 
00937 
00327 
00000 
00000 
00606 
00000 
00000 



000000000000 



0000 3 
000000 
4 00000 
00000 
00000 
00000 
00000 
00000 



01210 
00012 
00331 
00000 
00000 
00012 
00000 
00000 



000000000000 



oooooooooooo 

000000 



000001004625 
00100E 



oooooooooooo 

000000 



oooooooooooo 

000000 



oooooooooooo 

000000 



006100000056 
TCOB 0/000* 



-012060000101 
TMI « J+ Oil 



OOOOOOOOOOOO 
000000 



050000000135 
CLA 50001* 



076700000011 
ALS 7X0009 



200001100122 
TIX +0181B 



002000002073 
TRA 0+00+, 



002000002723 
TRA 0+OOGC 



002000004251 
TRA O+OOKR 



-162700010607 
TSL »G0167 



000020000000 
00+000 



000044000340 
0OM03- 



100000000006 
TXI 800006 



0020000D41S.I 
TRA 0+OOJJ 



-16270C003026 
TSL *GOORF 



000000000000 
000000 



oooooooooooo 

00CC0O 



oooooooooooo 

OOOODO 



-002200000050 
TRCB -BOOOO 



062200OD0101 
STD 6B0011 



OOOOOOOOOOOO 
000000 



-170400000021 
TMT *4000A 



-073400107060 
PDX PJ08YO 



00200CQ0005S 
TRA 0*000* 



00200000211) 
TRA 0+00»i 



002000002571 
TRA 0+COE/ 



00200000715? 
TRA 0*001 



00200001036 
TRA 0+01JV 



01000007777? 
TZE 10071 



0001700016T' 
01. YO* 



3122627062*0 
TXH IBSYS 



Figure 4. Octal Dump Format 
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The page heading is always provided if any dump 
parameters exist for the message number. Fields in the 
page heading pertaining to the time of day or elapsed 
time are printed only when the interval timer is in 
operation. 

The console panel is always provided if any dump 
parameters exist for the message number. This infor- 
mation includes: 

1. The octal contents of location s.sclk 

2. The bcd contents of location s.sdat 

3. The number of minutes for which the current 
job has run 

4. The contents of the registers 

5. The settings of the sense switches and the entry 
keys 

6. The settings of the Overflow and Divide Check 
indicators 

The system panel is an option that provides the unit 
control blocks and system control blocks for each at- 
tached unit in the Symbolic Units Table. 

The format of the core storage dump is specified by 
the dump parameters. 

The external storage dump is another option that 
can be specified in the dump parameters. The follow- 
ing information is provided: 

1. Symbolic unit containing information to be 
dumped 

2. Type of device, channel, and unit, all identical 
to information provided in the attach macro-instruc- 
tion during system assembly 

3. Machine interface, select address, and subaddress 

4. Number of the file containing information to be 
dumped on the system unit 

5. Number of the record within the file to be dumped 

6. Number of words in the record (in octal) 

7. Number of words in the record ( in decimal ) 
The mode of each record dumped is indicated by 

one of the following codes: 

Binary coded decimal 

Binary 

Redundancy error ( unreadable ) 

If there is an indication that the record is in the wrong 

mode, this record and subsequent records are read in 

the alternate mode. If a record is redundant, it is listed 

in the mode in which it was requested, the error is 

indicated, and the mode is not switched. However, 

certain devices give no indication of whether the 

record was bcd or binary. 

Errors that occurred on the units that were dumped 

are noted in the listing. Errors on units used by the 

Dump program are noted on the typewriter and in the 

listing, and are ignored. 



RECORD IN BCD 
RECORD IN BIN 
RECORD IN RDN 



Message Code Numbers 

The message code numbers that identify each set of 
parameters consist of five digits in the following for- 
mat: 

Ten Thousands Position: 

1. Message without pause. 

2. Pause that requires a specified manual action be- 
fore continuing 

3. Pause that requires a choice of specified manual 
actions before continuing 

The code is not used as there are no dead-end halts 
in the Operating System. 
Thousands Position: 

0. For ibm use only 

1. The general policy is that a 1 will not be used in 
this position until all possible uses of in combination 
with the hundreds position have been exhausted 

2. For ibm use only 

Hundreds Position: (This is used to designate the 
programming system in which the error occurred. ) 

1. ioex, ioop 

2. iols, iobs 

3. Sort/Merge 

4. Utilities 

5. Supervisors 

6. Simulators and Peripheral Programs 

7. Fortran iv compiler 

8. cobol compiler 

9. Macro Assembly Program or Loader 

Tens and Units Positions: ( These positions are to be 
used to ensure that every code format will be unique 
and are left to the discretion of the programmer. ) 

X1500 - X1549 System Editor 

X1550 - X1599 Processor and Input/Output 
Editors 

X1900 - X1999 Loader ( ibldr ) 

General Purpose Assignments: 

10000 The message operator call to dump 

13000 No Message 

Dump Parameters 

Associated with each error number is a sequence of 
parameters assembled in ibdmp2. The parameters in- 
clude one word that identifies the error, a sequence of 
words that describe the error message to be typed, a 
series of words that describe the error message to be 
listed on the system output unit, and words that de- 
scribe the portions of core storage or external storage 
media to be dumped. 
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Identifier 

The word that identifies the error has the following 

format: 

PZE pointr„errno 

where: 

pointr 

is the location of the identifier of the next error sequence and 
is equal to zero to terminate a sequence of pointers. 

errno 

is the five-digit error number. 

Error Messages 

Each word in the error message sequence has the fol- 
lowing form: 

pfx loc, t, count 

where: 

pfx 

consists of bits 0, 1, and 2, which have the following defini- 
tions : 

BIT DEFINITION 

— The sequence continues. 

1 — This is the final parameter in the sequence. 

1 — This is a sequence of an error message. 

1 — This is the entry point to a special editing 
routine. 

2 — The data is in core storage with the Dump 

program. 
1 — The data is in the core storage area of the 
calling program, which may have been over- 
laid, and may be found on the checkpoint 
unit. 

loc, t 

is the location of the first word of a sequence of BCD words 
to be included in the error message. The t may be index regis- 
ters 1, 2, or 4, loaded by the transfer instruction (TSX) to 
S.SDMP. If bit 1 of the prefix is 1, loc, t is the entry point of a 
special editing routine assembled with IBDMP. The prefix bits 
and 2, and the count are not interpreted. The format of param- 
eters for the special editing routine may be defined by specifica- 
tions for that routine. Return is to location IDPSC. 
count 

is the number of words starting at location loc, t to be in- 
cluded in the error message. Indirect addressing of parameters 
is indicated by a — 1 in the decrement of a parameter. The loca- 
tion and count are found in the location specified by loc, t. In- 
direct addressing is not available if pfx bit 1 is 1. 

If information, directly or indirectly addressed, is 
not available because s.scki is not provided, a word 
of asterisks will be substituted. 

For a special editing routine to have access to data 
that may have been overlaid and that may be found 
on the checkpoint unit, a dummy message parameter 
of the following form: 

PON loc, t, erase 

may be used before the following parameter: 

PTW loc, t 

The Dump program will retrieve the data word at 
loc, t and will store it in location erase. If this word 
has been overlaid and s.scki is not provided, erase will 
be set to zero. The Dump program can differentiate 
between a message parameter, a word retrieval, and 
indirect addressing, because the length of a segment 



of a message must be fewer than 200 words. Location 
erase may not be within the Nucleus and must be 
below 77777. 

There must be a separate sequence of parameters for 
the on-line and the listed messages. The type param- 
eters must be specified first, followed by the list 
parameters. Each of the error-message sequences must 
be terminated by a parameter with pfx bit equal to 
1. If a message is not to be typed or listed, the mee 
parameter must be supplied. If a special editing rou- 
tine has completed a message, the parameter counter 
must point to an mze parameter upon return to the 
Dump program. 

Storage to Be Dumped 

A sequence of sets of dump parameters follows the two 
sequences of message parameters. Each set of dump 
parameters consists of three words of the following 
form: 



pfx 


S.Sunn, 


, format + mode 


PZE 


from 




PZE 


to 





where: 

pfx 

has the following interpretation: 

Bit — The sequence continues. 

1 — This is the final set of parameters in ihe 
sequence. 
Bit 2 — The parameters are in core storage with 

IBDMP. 
1 — The parameters are in the core storage 
area of the calling program, which may 
have been overlaid, and may be found 
on the checkpoint unit. This is signifi- 
cant only for indirect addressing of 
parameters. 
S.Sunn 

is the function to which the external storage medium is 
assigned; to dump core storage, this field must be zero. 

One of the following codes is used to specify the 
format: 

1 — Octal ( single line ) 

2 - BCD ( single line ) 

3 - Octal with BCD ( double line ) 

4 — Octal with mnemonics ( double line ) 

5 — Octal with mnemonics and BCD ( double line ) 

If a code is not specified, an error message is given. 

Samples of the formats are shown in the section 
"The Device Print Program" in the publication IBM 
7040/7044 Operating System (16/32K): Programmers 
Guide, Form C28-6318. 

The mode is significant for external storage media 
only. It indicates the method of reading from the ex- 
ternal device as follows: 

8 -BCD 
— Binary 

The symbols from and to specify the inclusive limits 
of the dump. 
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For external storage media, the sequential file num- 
ber is in the decrement and the record number is in 
the address. 

Indirect addressing is indicated by a first parameter 
of the form: 

pfx loc, t, — 1 

where: 

pfx 

is as specified above, 
loc, t 

is the location in which the set of parameters may be found. 

When indirect addressing is used, the remaining two 
words are not provided. 

If a dump parameter, directly or indirectly ad- 
dressed, is not available because s.scki is not provided, 
the message dump parameter overlaid and lost will 
be listed. 

If the parameter list is terminated by an mze word, 
the remaining two parameters in the set need not be 
supplied. 

To provide an error sequence that does nothing, at 
least the following parameters must be supplied: 



PZE 


* + 6, errno 


MZE 


TYPE MESSAGE 


MZE 


LIST MESSAGE 


MZE 


DUMP CORE 


PZE 




PZE 





00005 


IBCLK 


777777765350 


00032 


IXTSP 


O0CO02OC6565 


00033 




TRA IXTPS 


00211 


S.SDAT 


00C302010604 


00213 


S.SCLK 


000001735064 


00214 


S.SCIS 


77777752720 


00217 


S.SCUR 


IBJOB 


00220 


S.SFAZ 


SPRING 


06564 




STA 33 



Figure 5. Assumed Contents of Specified Core Storage Locations 



1 


8 


16 










REM 


STORAGE PROTECT 


TRAP 


IXTPS 


ICT 








•INHIBIT TRAPS 




SXA 


IXTP3.4 






SAVE WORKING REGISTER 




LXD 


IBTSP, 4 






LOAD ERROR INDICATOR 




TXL 


IXTP2.4.0 






IS ERROR INDICATED 




TXH 


IXTP2.4.3 






YES, IS INSTRUCTION RPM 




LXA 


IBTSP, 4 






YES. LOAD LOCATION + 1 OF RPM 




TXH 


IXTP2.4, IP2ND*1 


IS RELEASE PERMITTED 




LXA 


IXTPS,'. 






YES, RESTORE WORKING REGISTER 




REM 


VIOLATION 


OF 


MEMORY PROTECT CONDONED 




MIT 


S.XTPS 






MAY TRAPS BE RESTORED 




RCT 








YES, RESTORE THEM 




TRA* 


IBTSP 






•RETURN TO REPRIEVED VIOLATOR 




REM 


VIOLATION 


OF 


MEMORY PROTECT CONDEMNED 


IXTP2 


STQ 


IXTP3+3 






HOLD MQ 




LDQ 


IBTSP 






SAVE ERROR CONDITION WORD 




STQ 


1XTP3+1 










LAC 


IBTSP, 4 






SAVE ERROR INSTRUCTION 




LDQ 


1,4 










STQ 


IXTP3+2 










LDQ 


IXT.P3 + 3 






RELOAD MQ 




TSX 


S.SDMP.4 






••THATS ALL CHARLEY 




PZE 


,,10505 








IXTP3 


PZE 


• • 










PZE 


ii )f ii 






LOCATION + 1 IN ERROR, .ERROR FLAG 




• «• 


** 






INSTRUCTION IN ERROR 




PZE 


** 






ERASEABLE j 



Figure 6. Routine Assumed to be in Core Storage 



Example of An Error Dump 

The following is an example of a call to dump in which 
the parameter sequence and the information typed and 
listed is the result of a violation of storage protection. 

1. Assume that the core storage locations shown in 
Figure 5 contain the information indicated 

2. Assume that the routine shown in Figure 6 is in 
core storage. 

3. Assume that the subroutine shown in Figure 7 is 
assembled in the Dump program and is used to edit 
the message. 

4. Assume that the parameter entries shown in 
Figure 8 have been assembled in the Dump program. 

The following message will be typed: 

10505 STO VIOLATN JOB DELETED 

The following message will be listed: 

10505 IBJOB SPRING 02160 STO VIOLATN LOCAT 
6564 STA INSTR 062100000033 

Following the message will be a page heading: 

10505 DUMP OF IBJOB SPRING DATE 3/21/64 JOB, 
START 000001735064 ELAPSED 
TIME 03.50 MIN PAGE 10 

A conventional panel print and the full core storage 
print will follow this message. 



1 8 


16 








REM 


PROCESS STORAGE 


PROTECT TRAP MESSAGE 




REM 


CALLING SEQUENCE 


FOR THIS ROUTINE 




REM 


CANNOT BE 


0VERLAIC BY DUMP RECORDS 




IDTPS LXA 


IDCX4.1 




LOAD CALLING LINKAGE 


TO IBDMP 


CAL 


3,1 




LOAD ERROR CONDITION 


PDX 


,2 




HOLD ERROR CODE 




SUB 


01 




COMPUTE ERROR LOCATION 


TSX 


ixocv+i.4 




$CONVERT LOCATION TO 


OCTAL 


SLW 


IDTPl + 3 




HOLD LOCATION 




TXL 


•♦2,2.'. 




IS BIT PATTERN VALID 


AXT 


0,4 




NO, SET TO INVALID MESSAGE 


CAL 


IDTP1.4 




LOAD TRAP TYPE 




SLW 


ICTP1+1 








CAL 


4,1 




LOAD INSTRUCTION IN 


ERROR 


TSL 


IDICV 




$C0NVERT INSTRUCTION 


TO OCTAL 


SLW 


I DT P 1 +.6 




HOLD LEFT HALF 




STQ 


IDTP1+7 




HOLD RIGHT HALF 




CAL 


4,1 




LOAD INSTRUCTION IN 


ERROR 


TSL 


IDMCV 




SCONVERT INSTRUCTION 


TO MNEMONIC 


SLW 


I DTP 1+4 




HOLD MNEMONIC 




TRA 


IDPSC 




•RETURN TO PARAMETER 


SCAN 


BCI 


l.STO VI 








BCI 


l.ILL VI 








BCI 


1 ,RPM VI 








1DTP1 BCI 


I, ILL VI 








BCI 


7, OLATN LOCAT INSTR 





Figure 7. Subroutine Assumed to he in the Dump Program 



1 


8 


16 






PZE 


»+7, , 10505 


POINTER 




PTW 


ICTPS 


EDIf RQ4JTINE 




MZE 


ICTPl+1,,2 


TYPE SEQUENCE 




MZE 


ICTPl+1,,8 


LIST SEQUENCE 




MZE 


0,,5 


DUMP CORE STORAGE 




PZE 









PZE 


-1 





Figure 8. Parameter Entries 
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Snapshot 

A snapshot routine can be used to dump the console 
and selected areas of core storage. This facility is use- 
ful for program debugging. 

Any number of snapshots can be taken during the 
execution of an object program. The following calling 
sequence is used to request snapshots : 



TSX 
PZE 



S.SNAP,4 
list„header 



where: 

list 

is the location of the first word of a list of parameters that 
specify the areas of storage for which snapshots are required. 
This list has the form: 

list PZE fword„count 

PZE fword„count 



PZE fword„count 

MZE fword„count 

fword is the location of the first word of the snapshot area, 
and count is the number of words that are to be preserved. 
The prefix MZE indicates the end of the list, 
header 

is the location of a BCD word that is to be used in the page 
heading when the snapshot is printed. 

When a request for snapshots is made, the Snapshot 
routine waits until all channel activity has been com- 
pleted. It then dumps the contents of the console ( the 
accumulator, mq, accumulator overflow and divide 
check indicators, sense switches, entry keys, and index 
registers) and the specified areas of core storage (in 
binary) on s.scki. When the execution of the object 
program has been completed, the System Dump pro- 
gram places this binary information with mnemonics 
and page headings in the format of an octal core stor- 
age dump and then writes it on s.soui. 



If there is no unit corresponding to s.scki, a request 
for snapshots is ignored. If the program is taking 
checkpoints on s.scki, it may not take snapshots. If tin- 
program is taking snapshots, it may not take check- 
points on s.scki. 



Execution of the Dump Program 

Execution of the Dump program involves execution 
of the Dump routine in the Nucleus before control is 
passed to the four major phases of the Dump program 
itself. The core storage used by the Dump program is 
shown in Figure 9. 

Dump Routine (S.SDMP) 

The Dump Routine in the Nucleus saves the console 
panel, copies the contents of the second and third 
quarters of the first 16K core storage locations onto 
the system checkpoint unit, and moves the first quarter 
of core storage to the third quarter. If a checkpoint 
unit is not attached, parts of the copied information 
are lost. The Dump routine uses the System Loader 
to load the first phase of the Dump program into the 
upper portion of this core storage area and transfers 
control to it. 

Phase 1 (IBDMP1) 

The first phase of the Dump program consists of a 
brief routine to copy the contents of the third and 
fourth quarters of the first of 16K core storage locations 
on the checkpoint unit to provide working space for 
Phase 2. Upon completion of this function, it returns 
control to the System Loader to load ioop2, iols, and 
the second phase. If the system checkpoint unit is not 
attached, this routine acts as a link to the second phase*. 



12K 



S.SDMP 



IBDMP1 



IBDMP2 



IBDMP3 




^ 



Ml 



Core storage occupied 



Core storage saved 



Figure 9. Use of Core Storage by the Dump Program 



Dump Program 25 



Phase 2 (IBDMP2) 

The second phase of the Dump program saves the 
calling sequence and error number, scans the Error 
Number Table in this phase, and pieces together the 
messages to be typed and/or written on the system 
output unit. 

It is possible that a parameter will refer to data in a 
location that has been overlaid by the Dump program. 
Phase 2 processes all parameters that refer to data in 
its own phase, or in that portion of the caller's record 
that has not been overlaid. It then reads in the portion 
of core storage that has been saved on s.scki and 
completes the messages with data from that record. 

This phase also sets up a communication region con- 
taining information supplied by the dump parameters 
for use by Phase 3 and, if applicable, writes the console 
and system panels on the system output unit. It calls 
the System Loader, which brings in the third phase 
of the Dump program. 

Phase 3 (IBDMP3) 

Using the information in the communication region, 
this phase writes on the system output unit the areas 
of core storage and external storage specified in the 
dump parameters. 

Traceback: This feature of the Dump program per- 
mits the path taken by the program to be followed 
backward from the location of the calling sequence to 
the Dump program by using the linkage director set 
up by the save macro-instruction to determine which 
subroutines were most recently entered. Each linkage 
is counted as one level of traceback. The level of trace- 
back is limited to prevent an unending loop of trace- 
back attempts. 



Snapshot Development: Whenever a programmer 
uses the Snapshot subroutine, a switch is set to indi- 
cate to the System Monitor that snapshots have been 
taken. Upon return of control to the System Monitor, 
the Supervisor calls the Dump program to interpret 
or develop the binary snapshot(s) on the system check- 
point unit. The Dump program rewinds the system 
checkpoint unit and writes the snapshots on the sys- 
tem output unit in the octal dump format. 

Return Facilities: These facilities are provided to 
permit the continuation of the calling program after 
a dump has been taken. Core storage is restored and 
control is passed to the final portion of the Restart 
routine. 

If a return is not specified after writing out the 
specified areas of storage, the Dump program returns 
control to the System Monitor, which continues to 
read cards. 

Dump Assembly Option 

The following symbol definition appears in the sym- 
bolic input: to the Dump program, phase 2 (ibdmp2): 

IDPDT SET n = l 

The coding to process the following features of the 
Dump program will be deleted if n is 0: 

1. Traceback 

2. System panel dump 

3. Dump of i/o device 

4. Listed error message text 

The deletion of these features shortens the Dump pro- 
gram and allows a full core dump when storage has 
been memory protected up to 8K. 
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Appendix A. IB JOB Deck Setup Using the 
Debugging Package (Figure 9) 
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Figure 10. Example of IBJOB Run Using Debugging Package 

Appendix B. System Restrictions with Debug 
Use 

1. Checkpoint and restart, or snap, may not be used 
with debugging if the Debug Work Unit is the system 
checkpoint tape. 



2. Location 2, used for linkage to the object-time 
debugging routines, should not be destroyed by the 
object program. 

3. The deck name of the debugging deck is /debug. 
This name should not be used for deck or control sec- 
tion names in the job to be debugged. 

4. The /debug deck will not stack debug requests. 
Thus, subroutines called from a debug request may not 
execute another debug request. This also applies to 
select and special routines. 

5. Real (floating-point) numbers may not be used in 
arithmetic operations if the user's computer is not 
equipped with the single-precision floating-point in- 
struction set. In addition, the Debug postprocessor 
must be reassembled in order to bypass conversion of 
any values to floating-point, double-precision, or com- 
plex modes when listing the debugging dumps (see 
the publication IBM 7040/7044 Operating System (16/ 
32K): Systems Programmers Guide, Form C28-6339). 

6. A Fortran statement number may not be used as 
a debugging request point when it is associated with a 
continue statement that terminates a do range when: 

a. the do increment (do 1000 1 = 1, 10, increment) 

is a variable, or 

b. within a subprogram with adjustable dimensions, 
the adjustable area is subscripted within the do 
range, and the subscript includes the do variable 
( i in the example above ) . 

7. Symbolic debugging cannot be used on decks 
loaded from the subroutine library, nor may a library 
name appear in the variable field of a $link card. 

8. The /debug deck will contain virtual references 
to the real sections that contain symbols referred to in 
the debug requests. These virtual references are gen- 
erated prior to processing of $name, $use, and $omit 
cards. As a result, even though sname cards may be 
used to retain at object time two or more control sec- 
tions of the same name, debugging references may be 
made to symbols in only one of these control sections. 
If these debugging statements refer to the symbols in 
the control section that has not been renamed, the user 
need make no further changes. However, if the control 
section being referred to is one which has been re- 
named, the user must provide a sname card that in- 
cludes the deck name /debug as a qualifier. 

For example, the following cards will change the 
control section named A to B in decki and will permit 
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debugging references to be made to the control section 
or to symbols within the control section: 

$NAME DECK1(A)=B 

$NAME /DEBUG(A)=B 

9. Under the following circumstances, deck names 
will be changed to names having the form /nnxyz, 
where nn are decimal digits and xyz are the three high- 
order characters of the original deck name: 

a. if debugging is specified for a relmod deck whose 
deck name matches one of the real sections 
created by an entry pseudo-operation (i.e., has 
length of zero) and the relative origin of the 
real section is not zero, or 

b. if the original deck name is of the form /nnxyz. 

If the deck name appears on a $use, $omit, or sname 
card, however, it will not be changed, and, therefore, 
debugging references to symbols within this deck may 
be undefined. 

10. = Rn may not refer to absmod decks. 

11. Debugging may not be used in an edit run. 

12. It is illegal to use symbolic debugging for a job 
using tcd, unless the debug requests refer to the link 
immediately preceding the sentry card or unless they 
refer to the parts of previous links that are not over- 
laid. No debugging action will occur until the last 
core load has been loaded. When the last core load 
has been loaded, debugging str's will be placed at 
the locations of all specified request points, whether 
or not they have been overlaid. 

13. Except for the information in the ibnuc Con- 



trol Dictionary, symbolic information about either 
absmod decks or absolute text in a relmod assembly 
will not be used by the postprocessor when debugging 
dumps are listed. Therefore, a debugging dump of 
an area assembled under an absolute origin will never 
include its symbol name. In addition, a debugging 
dump of an instruction that refers to this area will not 
include as a part of the variable field the symbol name 
of the area. Modal information will be used to deter- 
mine the format of a debugging dump of a portion 
of core storage that has been assembled under an 
absolute origin only if the element in the list or dump 
statement is one of the following: symbol, symbol 
(subscripts), or (loci, loc2, mode). Otherwise the 
mode will be considered octal. 

14. siedit cards may not be placed following the 
debugging packet of a job run. siedit cards may be 
located preceding the debugging packet, but the oc- 
currence of a sibdbl card will terminate $iedit control 
and return to s.sini for input. 

15. The copy feature cannot be used in a run which 
includes load-time symbolic debugging. If copy is 
specified, it will be ignored. 

16. The user cannot specify debug requests in stor- 
age-protected areas, although he can dump portions 
of storage-protected areas. 

17. If the system checkpoint unit is used as the 
Debug Work Unit, it cannot be assigned to the same 
physical unit (logical unit for disk or drum) as the 
unit for the load file. 
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A page number in italics indicates that the designated refer- 
ence is of particular importance. 

= A 9,12,14 

absolute location ( see location, absolute ) 

accumulator 13, 16 

address, base 16 

alphameric mode ( see mode, alphameric ) 

AND 11 

arithmetic expression ( see expression, arithmetic ) 

arithmetic operators 10 

arithmetic statement 10, J I 

array 12, 13, 14, 15, ; 18 
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$CBEND 6 

checkpoint and restart 27 
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statement 6, 7 
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compile-time 6, 7 
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DISPLAY verb ... 6, 7 

DO statement 27 

double-precision mode (see mode, double-precision) 

dump marker option 8, 9 

dump parameters 20, 22, 24, 26 

dump routine 25 

DUMP statement 13 
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$ENDCH B 

$ENTRY .8,28 

EQU ( see pseudo-operations ) 

error message 6, 20, |J3 
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exponentiation 7, 10 

expression 10, 11, 13, J. 6 

arithmetic 10, 11, 13, 16, 17 

logical 10, U, 16 

FATAL option 6,7 

floating-point mode (see mode, floating-point) 

floating-point number 10, 12, 14 

FORTRAN IV 
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functions 10 
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hierarchy of modes JO 
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$IBFTC 8,J5 

IBLDR ,5 

$IBMAP 5, J5 

IF statement 11,17 
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IOCS 8,9,20 
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TOBOU a, 9 
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KEEP (see pseudo-operations) 

LINE MAX « 

$LINK 8,27 

LIST statement 12, 13,28 

load-time 5, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 28 

location 9, 12, 14, 15, 17, 20, 23, 24, 25, 27 

absolute 9, 12, J 4 

relative 9, 12, 14, J 5 

logical expression (see expression, logical) 
logical operators ( see operators, logical ) 

logical variables Jl 

MAP 5, 8, 12, 14, 15, 19 

marker 6, 8, 9 

compile-time 6 

load-time 8. 9 

mode 9, 11, 12, 14, 15, 28 
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complex number 9, 14, 15 

double-precision 9, 14, J 5 

fixed point 12,14 

floating point 9, 12, 1 4 

logical 1U14 

octal 9, 11, 12, 14 

supplying to the debugging dictionary J5 

symbolic instruction 11,. 14 
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$NAME 27,.28 

NAME statement 10, 12*14 

= NEW 14 
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ON statement 7, 1 1, 12, 16 

operators 10, 11 
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logical 11 
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output editor 9 
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BES 15 
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ENTRY 28 

EQU 15 
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SYN 15 

TCD 28 
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$REDEF 9, 10, 14, 15 

relational operators ( see operators, relational ) 

restart 27 

RETURN statement 14 
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SNAP 27 

snapshot 25, 26 
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source deck 7, 8 

COBOL 8 

FORTRAN 8 

MAP 8 

STR 9,28 
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STOP statement 14 

subroutines 9, 13, 14, 27 
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FORTRAN 9 

library 27 
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Supervisor 20, 22 

symbol 9, 10, 12, 13, 14, 15, 27, 28 
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system restrictions 7, 27, 28 

system units 6, 9, 13, 19, 22, 23, 25, 26, 27 

checkpoint 19, 23, 25, 27 

output 6, 9, 13, 22, 26 

utility 6 

TCD (see ps;eudo-operations ) 

traceback 26 

TRAP MAX option 8 

unconditional statement 12 

$USE 28 
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subscripted 10 

work unit ( see debugging work unit ) 

WRITE statement 13 
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